Fix broken links in the docs by alexander-yevsyukov · Pull Request #341 · SpineEventEngine/validation

alexander-yevsyukov · 2026-10-30T18:31:28Z

The documentation site now serves jQuery as a file instead of inlining it
(SpineEventEngine/site-commons#39). Before, Lychee stopped extracting links at
the inlined script, so check-links only saw each page's <head>. Now it sees
every link, and 9 links in these docs fail. SpineEventEngine/documentation#96 lists
them in a temporary .lycheeignore; this PR fixes them at the source.

Fixes

running-builds.md, documentation-guidelines.md: .agents/guidelines
is now a symlink into the shared agents submodule, so the old
validation/blob/master/.agents/… URLs 404. The links now point to
guidelines/running-builds.md and guidelines/documentation.md (the renamed
documentation-guidelines.md) in SpineEventEngine/agents. The plain-text path
in testing-strategy.md is updated to match.
Gradle Plugin Portal: plugins.gradle.org/plugin/io.spine.validation
returns 400 because the plugin is not on the Portal. The build applies
java-gradle-plugin but not com.gradle.plugin-publish. The plugin marker
io.spine.validation:io.spine.validation.gradle.plugin is published to GitHub
Packages and the Artifact Registry (snapshots), next to the libraries.
"Build, packaging, and release" now says so: the link is gone, and the
diagram and the publication text name the repositories the plugin really
goes to.
EMBEDDING.md: SpineEventEngine/embed-code-go moved it to
showcase/embedding/README.md, which its README calls the "embedding guide".
Developer's guide links: ../06-developers-guide/ and ../../developer/
match no page (developer/ has no _index.md). The theme's relative-link
resolver passes them through, and they end up at /06-developers-guide/ and
/developer/. They now point to developer/overview-and-audience.md, the
guide's first page, which docs/validation/_index.md already links to.
typical_custom_option.jpg: 1810c30 (moving the guides into user/
and developer/) deleted the image instead of moving it. It is restored next
to user/05-custom-validation/_index.md (same blob, 5880f4e).

Lychee also flagged embed-code-go/tree/master/bin in the module version the
documentation site pins (6465029). Those links are already fixed on master.

The version is bumped to 2.0.0-SNAPSHOT.470 for the Version Guard. The
embedded version.gradle.kts snippet, the plugin version embedded in "Adding
to build", and the dependency reports are updated to match.

docs/_preview now uses site-commons 1c7c5ef, the latest master. It serves
jQuery as a file (SpineEventEngine/site-commons#39), compiles the styles with
Dart Sass (SpineEventEngine/site-commons#40), and declares go 1.27.3, which
raises the preview's go line to match.

`config` update

./config/pull brings config to 3a0d13a6. Its Check Links workflow now
finds a Hugo config in docs/_preview/ (SpineEventEngine/config#827) and
installs Dart Sass 1.99.0 for Hugo 0.169.0, so this repository's link check
actually builds and checks the site. No local dependency pin went down this
time.

The pull also exposed a missing dependency in jvm-runtime. Gradle reported
that kspKotlin reads generated/main/java without depending on
generateProto, which writes it. KSP reads the Kotlin source set, which lists
generated/main/java and generated/main/grpc with no build dependency.
Only the Java source set carries builtBy(generateProto), and that was so
before the pull too.

What hid the gap was dokka-setup.gradle.kts. It used to call
tasks.findByName("kspKotlin") in afterEvaluate, which creates the task
early and, as a side effect, gave it the dependency. The pull's lazy
tasks.named { … } no longer does (restoring only the old
dokka-setup.gradle.kts makes the clean build pass again). The commit message
of e967e68 blames configureTaskDependencies() instead; I tested that, and
the old helper alone does not help.

jvm-runtime/build.gradle.kts now declares kspKotlin → generateProto and
kspTestKotlin → generateTestProto. The dependency reports are regenerated
for the newer tool versions. The pull also raised CoreJvm Compiler to .099, so
"Adding to build" embeds the new io.spine.core-jvm version.

While there, jvm-runtime/build.gradle.kts lost two unused imports and its
classpath(CoreJvmCompiler.gradlePlugin). That entry is a leftover from McJava:
no plugin from it is applied, and the module builds the same without it.

Verification

I built the validation docs preview with Hugo 0.169.0 and Dart Sass 1.99.0
(hugo -e development plus hugo server -e development), then ran Lychee
0.24.2 with this repo's lychee.toml:

master with site-commons 9216e48: 9 errors, the links listed above.
This branch with site-commons 1c7c5ef: 0 errors (3403 links, 429 unique).

After the config update, I ran the new workflow's detect step locally, and it
resolves work_dir=docs/_preview. Then I ran the link check the way the
workflow does, against hugo server on port 1313: 0 errors. Before this
update, the check-links job skipped this site with "No Hugo site found".

./gradlew build passes. I also rebuilt jvm-runtime from clean with
--no-build-cache, so that generateProto and kspKotlin really ran.

Fixes #340

🤖 Generated with Claude Code

Lychee found these links broken once the documentation site stopped inlining jQuery: - `running-builds.md` and `documentation-guidelines.md` no longer live in `.agents/`. Link `running-builds.md` and `documentation.md` in the shared `agents` repository instead. - The plugin is not published to the Gradle Plugin Portal: the build applies `java-gradle-plugin` but not `com.gradle.plugin-publish`, and the plugin marker sits in GitHub Packages and the Artifact Registry. Drop the Portal link and describe the actual destinations. - `EMBEDDING.md` became `showcase/embedding/README.md` in `embed-code-go`. - The user guide linked `../06-developers-guide/` and `../../developer/`. Neither is a page, so the theme resolved them to the site root. Link the first page of the Developer's guide. - Restore `typical_custom_option.jpg`, which was deleted rather than moved when the guides moved into `user/` and `developer/`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

chatgpt-codex-connector · 2026-10-30T18:31:41Z

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-30T18:32:53.997214Z	`4f9577c`	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Copilot

🟡 Changes recommended

The plugin setup link points to a nonexistent directory when the Markdown is viewed on GitHub, leaving repository readers unable to reach the instructions.

1 open issue

Link to the actual adding-to-build.md file · New

What changed in this PR

This PR repairs links in the Validation documentation identified by issue #340 and corrects the explanation of where the Gradle plugin is published.

Changes:

Update developer-guide navigation and links to shared guidelines and embedding documentation.
Replace Gradle Plugin Portal references with the actual Maven publication destinations.
Bump the version to 2.0.0-SNAPSHOT.470 and synchronize the embedded snippet and dependency reports.

File	Description
`version.gradle.kts`	Bumps the snapshot version.
`docs/dependencies/pom.xml`	Synchronizes the dependency-report version.
`docs/dependencies/dependencies.md`	Refreshes report versions and timestamps.
`docs/content/docs/validation/user/05-custom-validation/summary.md`	Corrects the developer-guide link.
`docs/content/docs/validation/user/05-custom-validation/pass-to-compiler.md`	Corrects the developer-guide link.
`docs/content/docs/validation/user/04-validators/implement-a-validator.md`	Corrects the developer-guide link.
`docs/content/docs/validation/user/04-validators/_index.md`	Corrects the developer-guide link.
`docs/content/docs/validation/developer/testing-strategy.md`	Updates the plain-text documentation-guidelines path.
`docs/content/docs/validation/developer/documentation/procedures.md`	Links to the shared documentation guidelines.
`docs/content/docs/validation/developer/documentation/embedded-examples.md`	Links to the relocated embedding guide.
`docs/content/docs/validation/developer/build-and-release.md`	Corrects publication details, updates the guidelines link, and synchronizes the version snippet.

_{Review effort: Balanced}

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

`configureTaskDependencies()` now wires the tasks lazily, so it no longer realizes them in `afterEvaluate`. That eager realization used to order `generateProto` before `kspKotlin` by chance. Without it, Gradle reports that `kspKotlin` reads `generated/main/java` (and `kspTestKotlin` reads `generated/test/java`) without depending on the task that writes it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The `./config/pull` raised `CoreJvmCompiler.version`, which `updateCoreJvmPluginVersion` writes into the examples. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The script no longer uses `SpinePublishing` or `StandardJavaPublicationHandler`. No plugin from `CoreJvmCompiler.gradlePlugin` is applied here. The classpath entry came in as `mcJava.pluginLib` with `apply(plugin = "io.spine.mc-java")` (fb62d71). It stayed after 53ada48 removed the `apply`, and later commits only renamed it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

codecov · 2026-11-02T17:28:23Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.96%. Comparing base (c72021e) to head (9e8ba80).

Additional details and impacted files

@@            Coverage Diff            @@
##             master     #341   +/-   ##
=========================================
  Coverage     93.96%   93.96%           
  Complexity      367      367           
=========================================
  Files            86       86           
  Lines          2271     2271           
  Branches        159      159           
=========================================
  Hits           2134     2134           
  Misses           93       93           
  Partials         44       44

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot

🟡 Changes recommended

The updated theme requires Dart Sass, but the documentation omits it from the prerequisites and installation steps, leaving site tasks failing when it is absent.

1 open issue

Document Dart Sass as a required docs build prerequisite · New

1 resolved since last review

Link to the actual adding-to-build.md file

_{Review effort: Balanced}

alexander-yevsyukov and others added 5 commits October 30, 2026 18:24

Bump version -> 2.0.0-SNAPSHOT.470

6a6b1e2

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Embed the bumped version.gradle.kts in the release docs

b9e7a16

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Avoid repeating "plugin" in the publication text

1641b39

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Update dependency reports

4f9577c

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot AI balanced review requested due to automatic review settings October 30, 2026 18:31

alexander-yevsyukov self-assigned this Oct 30, 2026

Copilot started reviewing on behalf of alexander-yevsyukov October 30, 2026 18:31

View session

Copilot AI reviewed Oct 30, 2026

View reviewed changes

Comment thread docs/content/docs/validation/developer/build-and-release.md Resolved

alexander-yevsyukov added this to v2.0 Nov 2, 2026

alexander-yevsyukov moved this to 🏗 In progress in v2.0 Nov 2, 2026

alexander-yevsyukov and others added 3 commits November 2, 2026 16:02

Embed Validation 2.0.0-SNAPSHOT.470 in "Adding to build"

c92ba5b

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Update site-commons

d9805c0

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Link to adding-to-build.md so the links work on GitHub

8290f71

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

alexander-yevsyukov mentioned this pull request Nov 2, 2026

Find Hugo configs in the _preview/ sub-tree in Check Links SpineEventEngine/config#827

Merged

alexander-yevsyukov and others added 5 commits November 2, 2026 16:53

Update shared agent tooling and config (./config/pull)

741ed5a

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Update dependency reports

9d9fd49

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Embed CoreJvm Compiler 2.0.0-SNAPSHOT.099 in "Adding to build"

0d60f1e

The `./config/pull` raised `CoreJvmCompiler.version`, which `updateCoreJvmPluginVersion` writes into the examples. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

alexander-yevsyukov requested a balanced review from Copilot November 2, 2026 17:33

Copilot started reviewing on behalf of alexander-yevsyukov November 2, 2026 17:34

View session

Copilot AI reviewed Nov 2, 2026

View reviewed changes

Comment thread docs/_preview/go.mod Resolved

alexander-yevsyukov merged commit 2754355 into master Nov 2, 2026
13 checks passed

alexander-yevsyukov deleted the fix-broken-doc-links branch November 2, 2026 17:38

github-project-automation Bot moved this from 🏗 In progress to ✅ Done in v2.0 Nov 2, 2026

This was referenced Nov 2, 2026

Update Validation docs and remove .lycheeignore SpineEventEngine/documentation#98

Merged

Update the documentation module and drop .lycheeignore SpineEventEngine/SpineEventEngine.github.io#565

Merged

Navigation Menu

Repository navigation

Fix broken links in the docs - #341

Fix broken links in the docs#341
alexander-yevsyukov merged 13 commits into
masterfrom
fix-broken-doc-links

alexander-yevsyukov commented Oct 30, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot commented Oct 30, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

codecov Bot commented Nov 2, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

alexander-yevsyukov commented Oct 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Fixes

config update

Verification

Uh oh!

chatgpt-codex-connector Bot commented Oct 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codex Review Summary

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

codecov Bot commented Nov 2, 2026

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

alexander-yevsyukov commented Oct 30, 2026 •

edited

Loading

`config` update

chatgpt-codex-connector Bot commented Oct 30, 2026 •

edited

Loading